The Planning and Scheduling API is a RESTful web service that enables Verizon Connect customers to integrate 3rd party back-office systems with REVEAL to create and manage work orders to review the vehicle s GPS data alongside the locations that their drivers are expected to visit.
The Planning and Scheduling (PAS) API is broken into multiple segments based on the object management within REVEAL. The following documentation will focus on the management of work order objects within REVEAL.
In order to apply a Status and/or Type for a work order, the Planning and Scheduling Status and Planning and Scheduling Type APIs will need to be reviewed. In order to create a Work Order, a Status and Type are required fields. If your account does not want to dynamically manage status and types, there are various ways to manage these required fields which will be noted more fully within the Status and Type documentation.
Planning and Scheduling Work Order API is offered as a RESTful web service
Standard REST verbs are applied: GET, POST, and PUT
o There are no DELETE methods for the Planning and Scheduling Work Orders API and work orders cannot be deleted within the REVEAL UI
Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created or deleted. The unique identifiers used within this API method set include:
o Work Order Number
o Driver Number
o Vehicle Number
o Work Order Status Code
o Work Order Type Code
o Stop ID
Work order management software handles the automation of scheduling, assigning, and tracking jobs for the mobile workforce industry.
The definition of a work order when integrated with REVEAL, includes the following:
The technician/driver is assigned to a single vehicle within REVEAL
A single work order is only assigned to one technician/driver
Multiple work orders can be assigned to one technician/driver
Scheduled at a defined Start Date and Time within a single day
Vehicle location and work order statusing are used to identify where and when the activity happened and if the stop was a match to the work order. REVEAL displays location and work order information together for customers to review and improve efficiencies within their businesses.
In some instances, work orders will be created before a driver assignment is made. For this scenario, the following guidelines will apply:
If no driver is provided, the POST Work Order API method will accept the request.
Within REVEAL, on the Live Map you can search for the work order by work order number.
You can also choose to plot UNASSIGNED work orders on the map.
Please note, if you choose to plot UNASSSIGNED work orders, you will only see Unassigned Work Orders plotting for the selected day.
Daily Report with Work Orders
Work Order Summary
Work Order Variance Report
REVEAL work order reporting logic assumes that the integration will provide details related to a work order s status or that the Field App will be used in order to track a work order s lifecycle. If there is no intention to provide work order status updates, REVEAL reporting logic can be switched to use the Scheduled Date information to compare with vehicle location information for matching. Using the Scheduled Date logic is not as accurate as Status comparison. By default, the work order linkage logic is set to Status, Customer Support can switch this setting for a REVEAL account by request.
On Time Arrivals
Vehicle Activity (Hours Worked)
Work Order On Site Time
Work Orders on Live Map
Timeline View with Work Orders
Replay with Work Orders
Note: The current
version of the Vehicle Update API does not support devices tracking Non-Powered
Assets. No information will return regarding Non-Powered Assets within
any of the following API methods.
The returned response will be restricted to the
Reveal account's data plan. If the information being queried is outside of the
data plan, a "400 Bad Request error "response will be returned.
For more details on your account's data plan
please reach out to Verizon Connect Customer Support
|
API Name |
Planning and Scheduling Work Orders |
|
Endpoint |
https://fim-stage.api.us.fleetmatics.com/pas/v1 |
|
Operation |
GET, POST, PUT |
The GET Work Order by Work Order Number method enables integration users to retrieve all the data that REVEAL has been sent related to a specific work order.
|
Operation and Path |
GET https://fim-stage.api.us.fleetmatics.com/pas/v1/workorders/<work
order number> HTTP/1.1 |
|
HOST |
fim-stage.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"WorkOrder": {
"ActualDateUtc": "2017-01-18T13:15:48.983",
"ActualDurationSeconds": 0,
"Address": {
"AddressLine1": "11241 Miromar Square Blvd",
"AddressLine2": "",
"Locality": "Estero",
"AdministrativeArea": "FL",
"PostalCode": "33928 ",
"Country": "USA"
},
"AddressResolved": true,
"ClientCustomerId": null,
"CreatedDateUtc": "2017-01-18T17:00:05.263",
"Description": "TECH MUST CLOCK IN",
"DriverNumber":
"777",
"Latitude": 26.425671,
"Longitude": -81.801965,
"ModifiedDateUtc":
"2017-01-18T16:58:55.4",
"OnSiteDurationSeconds": 0,
"RadiusInKm": 0.322,
"ScheduledDateUtc": "2017-01-18T16:59:50",
"ScheduledDurationSeconds": 0,
"StatusChangeDateUtc": "2017-01-18T13:16:47",
"WorkOrderNumber": "595067-03CARA-374",
"WorkOrderStatusCode": "Open",
"WorkOrderTypeCode": "INT LMSW"
},
"_links": {
"Self": {
"Href": "http://api.us.fleetmatics.com/PAS/v1/workorders/595067-03CARA-374"
}
}
}
The GET Current Work Order Status by Work Order Number enables the integration user to retrieve the current Work Order Status applied to the work order. Users may invoke this method to track the work order s lifecycle within REVEAL.
In order to apply a work order status to a work order in REVEAL the status type must first be created to be recognized using the Planning and Scheduling Work Order Status API. Available work order statuses can be reviewed within REVEAL s Admin section under Work Order Preferences.
|
Operation and Path |
GET https://fim-stage.api.us.fleetmatics.com/pas/v1/workorders/
<work order number>/status HTTP/1.1 |
|
HOST |
fim-stage.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"StatusChangeDateUtc": "2017-01-18T13:16:47",
"WorkOrderStatusCode": "InProcess",
"WorkOrderStatusDescription": "InProcess Work Order.",
"WorkOrderStatusType": "InProcess"
}
The POST Work Order method enables integration users to create work orders within the REVEAL account.
The request body must have the following information completed for the work order:
{
"ActualDateUtc": "",
"ActualDurationSeconds": null,
"Address": {
"AddressLine1": "4444 East Ridgewood Drive",
"AddressLine2": null,
"Locality": "Seven Hills",
"AdministrativeArea": "Ohio",
"PostalCode": "44131",
"Country": "USA"
},
"ClientCustomerId": null,
"Description": null,
"DriverNumber": "777",
"Latitude": 0.0,
"Longitude": 0.0,
"OnSiteDurationSeconds": 0,
"RadiusInKm": ".322",
"ScheduledDateUtc": "2017-01-13Z18:00:00",
"ScheduledDurationSeconds": null,
"StatusChangeDateUtc": null,
"WorkOrderNumber": "WO-2518-2029",
"WorkOrderStatusCode": "InProcess",
"WorkOrderTypeCode": "ALM"
}
|
Operation and Path |
POST
https://fim-stage.api.us.fleetmatics.com/pas/v1/workorders HTTP/1.1 |
|
HOST |
fim-stage.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
When the POST Work Order is invoked successfully the response will include the work order object s details within the response.
{
"ActualDateUtc": null,
"ActualDurationSeconds": null,
"Address": {
"AddressLine1": "4444 East Ridgewood Drive",
"AddressLine2": null,
"Locality": "Seven Hills",
"AdministrativeArea": "Ohio",
"PostalCode": "44131",
"Country": "USA"
},
"AddressResolved": false,
"ClientCustomerId": null,
"CreatedDateUtc": "2017-01-18T21:38:28.78",
"Description": null,
"DriverNumber":
"777",
"Latitude": 0,
"Longitude": 0,
"ModifiedDateUtc":
"2017-01-18T21:38:28.78",
"OnSiteDurationSeconds": 0,
"RadiusInKm": 0.322,
"ScheduledDateUtc": "2017-01-13T18:00:00",
"ScheduledDurationSeconds": null,
"StatusChangeDateUtc":
null,
"WorkOrderNumber":
"WO-2518-2029",
"WorkOrderStatusCode":
"InProcess",
"WorkOrderTypeCode": "ALM"
}
The POST Work Order Status method enables integration users to update a work order s status to track the lifecycle of the work order. Work orders need to minimally have IN PROCESS and COMPLETED statuses for REVEAL to calculate reporting metrics and match the work order to vehicle location information.
If your account is not planning to status a work order, there is an option for your work order reporting to use Schedule Date UTC to match against vehicle location information. The match rate is not as accurate, but a Customer Support representative can adjust the logic referenced on request.
The request body must have the following information completed to update a work order status:
{
"WorkOrderStatusCode": "Complete",
"WorkOrderStatusDescription": "Complete",
"WorkOrderStatusType": "Complete"
}
|
Operation and Path |
POST
https://fim-stage.api.us.fleetmatics.com/pas/v1/workorders/<work order
number>/status HTTP/1.1 |
|
HOST |
fim-stage.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
Similar to a PUT method, the POST Work Order response will not return an object review. The response will be limited to a set of standard HTTP codes:
Successfully edited work order will return a 200 code
Unfound Place IDs, or the unique identifier used for the call, will return a 404 error
Bad requests, typically due to an error in the call s content, will return a 400 error
Invalid tokens or an Authorization problem will return a 401 error
If the service is unavailable at the time the call was made a 500 error will return
The PUT Work Order by Work Order Number method enables integration users to update an existing work order s meta data within REVEAL.
The PUT method cannot be used to update a work order s status. To update a work order status, the POST Work Order Status method will need to be invoked.
The request body must have the following information completed for the work order:
{
"ActualDateUtc": "",
"Address": {
"AddressLine1": "3000 East Ridgewood Drive",
"AddressLine2": null,
"Locality": "Seven Hills",
"AdministrativeArea": "Ohio",
"PostalCode": "44131",
"Country": "USA"
},
"ClientCustomerId": null,
"Description": null,
"DriverNumber": "777",
"Latitude": 0.0,
"Longitude": 0.0,
"OnSiteDurationSeconds": 0,
"RadiusInKm": ".322",
"ScheduledDateUtc": "2017-01-13Z18:00:00",
"ScheduledDurationSeconds": null,
"WorkOrderNumber": "WO-2518-2029",
"WorkOrderTypeCode": "ALM"
}
|
Operation and Path |
PUT
https://fim-stage.api.us.fleetmatics.com:443/pas/v1/workorders/<work order
number> HTTP/1.1 |
|
HOST |
fim-stage.api.us.fleetmatics.com |
|
Accept |
application/json |
|
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
PUT methods will not return an object review. The response will be limited to a set of standard HTTP codes:
Successfully edited work order will return a 200 code
Unfound Place IDs, or the unique identifier used for the call, will return a 404 error
Bad requests, typically due to an error in the call s content, will return a 400 error
Invalid tokens or an Authorization problem will return a 401 error
If the service is unavailable at the time the call was made a 500 error will return
The following list provides all the possible fields that may be requested or retrieved when working with the Planning and Scheduling Work Order API. The RAML file or the method documentation above describes the object requirements for request and response fields to be used per call. This list should only be used for reference for field definition.
|
Field |
JSON
Formatted Sample |
Field
Notes and Default Values |
|
ActualDate Utc |
{ "ActualDateUtc":
null, |
The Actual Date field is
used when a PUT is invoked to change the Scheduled Date for a work
order. |
|
ActualDurationSeconds |
"ActualDurationSeconds":
null, |
REVEAL will calculate the
actual duration value based on the status information provided. If no status information is provided this
value may be provided by the work order provider. |
|
Address |
"Address": { "AddressLine1": "4444
East Ridgewood Drive", "AddressLine2": null, "Locality": "Seven
Hills", "AdministrativeArea":
"Ohio", "PostalCode":
"44131", "Country": "USA" }, |
Address contains the
global standards for address components:
Address Line 1 location
specific identification such as a house number
Address Line 2 additional information
to identify location such as an apartment number
Locality city, town, etc.
Administrative Area state,
province, etc.
Postal Code
Country Address components are not
required if the coordinates are provided for the work order. If address components and coordinates are
both provided, the work order will be created referencing the coordinates. |
|
AddressResolved |
"AddressResolved":
false, |
Boolean field. When retrieving a work order s details if
the work order location was successfully geocoded by Google the flag will be
set to true. |
|
ClientCustomerId |
"ClientCustomerId":
null, |
Boolean field for
deprecated service parameter, defaults to Null |
|
CreatedDateUtc |
"CreatedDateUtc":
"2017-01-18T21:38:28.78", |
The date and time stamp in
UTC that the work order object was created within REVEAL. The default value will be the current date
and time stamp when the work order was invoked. |
|
Description |
"Description": null, |
This is not a required
field. A string may be provided in
order to display instructions or notes about the work order to the
technician/driver. |
|
DriverNumber |
"DriverNumber":
"777", |
The Driver Number is the
unique identifier that will be used to reference the driver within the
API. The Driver Number is not a
mandatory field within the REVEAL account, but is required for the API. |
|
Latitude |
"Latitude": 0, |
Either the Address
components or the coordinates must be provided to create a work order. If both the address and coordinate fields
are supplied, the coordinates will be used for reference to geocode the work
order s location. |
|
Longitude |
"Longitude": 0, |
Either the Address
components or the coordinates must be provided to create a work order. If both the address and coordinate fields
are supplied, the coordinates will be used for reference to geocode the work
order s location. |
|
ModifiedDateUTC |
"ModifiedDateUtc":
"2017-01-18T21:38:28.78", |
If the work order object
is modified after the creation date, the last modified date will be presented
within the response. |
|
OnSiteDurationSeconds |
"OnSiteDurationSeconds":
0, |
This is not a required
field. If there is an estimate for the
time that the technician should be on site at the work order the value may be
provided in seconds. Following the work
order s completion if status details were provided, this value will be
overwritten with the status calculation to determine the on-site duration. |
|
RadiusInKm |
"RadiusInKm":
".322", |
The designated radius in
kilometers used to create the radius around the work order. |
|
ScheduledDateUtc |
"ScheduledDateUtc":
"2017-01-13Z18:00:00", |
The Scheduled Date and
Time for the work to be started or the technician s scheduled time to be on
site. |
|
ScheduledDuration Seconds |
"ScheduledDurationSeconds":
null, |
The Scheduled Duration in
Seconds that the work order job is estimated to take. This value will not be overwritten by
REVEAL s calculation and will be used for reporting variances. |
|
StatusChangeDateUtc |
"StatusChangeDateUtc":
null, |
The date and time when the
work order s status was applied. |
|
WorkOrderNumber |
"WorkOrderNumber":
"WO-2518-2021", |
Work Order Number is a
required field for a work order to be created within REVEAL and must be
unique within an account. |
|
WorkOrderStatusCode |
"WorkOrderStatusCode":
"InProcess", |
Work Order Status Codes
are created using the Planning and Scheduling Work Order Status API. All available work order status codes can
be found within REVEAL s Admin section under Work Order Preferences. A work order status is used to update a
work order s lifecycle for tracking purposes. |
|
WorkOrderStatus
Description |
"WorkOrderStatusDescription": "InProcess Work Order.", |
When creating work order
statuses within a REVEAL account there is an optional field for a Description
to be provided. If the status was
created with a Description the GET method for a work order s current status
will return the description field. |
|
WorkOrderStatusType |
"WorkOrderStatusType": "InProcess" } |
|
|
WorkOrderTypeCode |
"WorkOrderTypeCode":
"ALM" } |
Work
Order Type Codes are created using the Planning and Scheduling Work Order
Type API. All available work order
types can be found within REVEAL s Admin section under Work Order
Preferences. A work order code is used
to describe or categorize the type of work scheduled, i.e. Trouble Call. |